From b5a2bba84071265ffd2c2327e710b8bee3318ea4 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Mon, 11 Jul 2016 16:55:10 +0100 Subject: [PATCH] docs: Improve gdk_window_create_similar_image_surface() The sizes passed are in device pixels and do not take into account the scaling factor of the window itself. We cannot change the semantics of the function, so let's at least add a warning for this trap door. --- gdk/gdkwindow.c | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c index b9c58430e2..5e91fcc884 100644 --- a/gdk/gdkwindow.c +++ b/gdk/gdkwindow.c @@ -10046,6 +10046,25 @@ gdk_window_create_similar_surface (GdkWindow * window, * Initially the surface contents are all 0 (transparent if contents * have transparency, black otherwise.) * + * The @width and @height of the new surface are not affected by + * the scaling factor of the @window, or by the @scale argument; they + * are the size of the surface in device pixels. If you wish to create + * an image surface capable of holding the contents of @window you can + * use: + * + * |[ + * int scale = gdk_window_get_scale_factor (window); + * int width = gdk_window_get_width (window) * scale; + * int height = gdk_window_get_height (window) * scale; + * + * // format is set elsewhere + * cairo_surface_t *surface = + * gdk_window_create_similar_image_surface (window, + * format, + * width, height, + * scale); + * ]| + * * Returns: a pointer to the newly allocated surface. The caller * owns the surface and should call cairo_surface_destroy() when done * with it. -- 2.30.2